<html>
    <head>
    <link rel="stylesheet" href="lmm.css" type="text/css" />
    </head>
<body class="lmm">
<!-- This file is part of the Lisp Machine Manual.	-*-Text-*- -->

<div class='chapter'>4. Locatives</div><p class='cindent'><!-- locative -->

<div class='section'>4.1 Cells and Locatives</div><p class='cindent' id='locative'><!-- cell -->

	A <font class="italic">locative</font> is a type of Lisp object used as a <font class="italic">pointer</font>
to a <font class="italic">cell</font>.  Locatives are inherently a more "low level" construct
than most Lisp objects; they require some knowledge of the nature of
the Lisp implementation.  Most programmers will never need them.

	A cell is a machine word which contains a (pointer to a) Lisp object.
A symbol has five cells: the print name cell, the value cell, the
function cell, the property list cell, and the package cell.  The value
cell holds (a pointer to) the binding of the symbol, and so on.
Also, an array leader of length <font class="italic">n</font> has <font class="italic">n</font> cells, and
an array of <font class="italic">n</font> elements has <font class="italic">n</font> cells provided the array is
not a numeric array.  However, a numeric array contains a different
kind of cell, which cannot be pointed to by a locative.

	There are a set of functions which create locatives to 
cells; the functions are documented with the kind of object to
which they create a pointer.  See <font class="lisp">ap-1</font>, <font class="lisp">ap-leader</font>,
<font class="lisp">car-location</font>, <font class="lisp">value-cell-location</font>, etc.  The macro <font class="lisp">locf</font>
(see (locf-fun))
can be used to convert a form which accesses a cell to one which
creates a locative pointer to that cell: for example,
<pre class="lisp">
(locf (fsymeval x)) ==&gt; (function-cell-location x)
</pre>

<div class='section'>4.2 Functions Which Operate on Locatives</div>
	Either of the functions <font class="lisp">car</font> and <font class="lisp">cdr</font> 
(see (car-fun))
may be given a locative, and will return the contents of the cell at
which the locative points.
<pre class="lisp">
<font class="main">For example,</font>
(car (value-cell-location x))
<font class="main">is the same as</font>
(symeval x)
</pre>

	Similarly, either of the functions <font class="lisp">rplaca</font> and <font class="lisp">rplacd</font> may
be used to store an object into the cell at which a locative
points.
<pre class="lisp">
<font class="main">For example,</font>
(rplaca (value-cell-location x) y)
<font class="main">is the same as</font>
(set x y)
</pre>

If you mix locatives and lists, then it matters whether you use <font class="lisp">car</font>
and <font class="lisp">rplaca</font> or <font class="lisp">cdr</font> and <font class="lisp">rplacd</font>,
and care is required.  For example, this function takes
advantage of <font class="lisp">value-cell-location</font> to cons up a list in forward
order without special-case code.  The first time through the loop,
the <font class="lisp">rplacd</font> is equivalent to <font class="lisp">(setq res ...)</font>; on later times
through the loop the <font class="lisp">rplacd</font> tacks an additional cons onto the end of the list.
<pre class="lisp">
(defun sort-of-mapcar (fcn lst)
  (do ((lst lst (cdr lst))
       (res nil)
       (loc (value-cell-location 'res)))
      ((null lst) res)
    (rplacd loc
	    (setq loc (ncons (funcall fcn (car lst)))))))
</pre>
You might expect this not to work if it was compiled and <font class="lisp">res</font>
was not declared special, since non-special compiled variables are
not represented as symbols.  However, the compiler arranges for
it to work anyway.
.eof
</body>
</html>

